Amiga Collections: Various/DevDisk 65 (1989)(DevWare PD).zip/DevDisk 65 (1989)(DevWare PD).adf/prosuite/fileio.doc

Text File | 1990-07-11 | 40KB | 1,028 lines

FileIO Requester
User and Programmer Manual
From the Amiga Programmer's Suite Book 1, by RJ Mical
Copyright (C) 1987, Robert J. Mical




This document describes the FileIO Requester, both for users of
the requester and for programmers who will create the requester.
The main sections of this document are:

    o  FROM THE USER'S POINT OF VIEW

    o  PROGRAMMER'S REFERENCE

    o  DEMO PROGRAM NOTES

    o  TECHNICAL REFERENCE

    o  USING THE AMIGA PROGRAMMER'S SUITE

    o  APPENDIX A:  FileIO Function Calls




============================================================================
=== FROM THE USER'S POINT OF VIEW ==========================================
============================================================================

This section presents the FileIO Requester from the user's point of view.
This is a rough example of the sort of documentation that might be supplied
to the end user of this FileIO Requester.



=== Welcome to the FileIO Requester ========================================

The FileIO Requester allows you an easy way to select which file you want
to use for input or output.  This section describes how you go about using
the FileIO Requester.

The FileIO Requester consists of several parts:

    o  the "Select a Name" gadgets which allow you to choose a file name
       simply by scrolling through a list of names until you find the one
       you want, pointing at the name and clicking the left mouse button

    o  the OK! gadget which you use to acknowledge that the name you've
       chosen is the one you wanted

    o  3 string gadgets which allow you to type in the name directly
       rather than using the "Select a Name" gadgets to find the file you
       want

    o  a NEXT DISK gadget which allows you to examine one disk after
       another

    o  the CANCEL gadget, which you use to when you've decided you don't
       want to select a file after all


The "Select a Name" gadgets present you with a list of file names and allow
you to use the mouse to scan easily through the list and select one of
the filenames simply by pointing at it and clicking.

The "Select a Name" gadgets consist of:

    o  a box of where some of the list of file names are displayed

    o  a slider which lets you scan quickly through the list of files

    o  an up gadget and a down gadget which allow you to move through the
       file list one name at a time


There are 3 types of entries in the list of file names.

At the top of the list are the file names that you can choose.  These
names are listed in alphabetical order.

At the bottom of the list there are special entries which allow you to move
around through the drawers of a disk, much like you move around through
drawers on the Workbench display.

The entries that start with the ">>>>" characters allow you to "open" a
drawer and examine the names of the files in that drawer.  For example,
when examining a Workbench disk, at the bottom of the list you would find
an entry that looked like ">>>> Demos" which means that you can go into
the drawer named "Demos".  If you selected ">>>> Demos" you would see,
after a short pause, a new list of file names:  the names of the files
that are in the "Demos" drawer.

In the "Demos" drawer you would also find a special entry,
"<<<< PRIOR DRAWER".  If you select this entry, you will move back to
the drawer that contained your current drawer.

An alternate way to change drawers is to type the name of the drawer you
want in the string gadget labelled "Drawer" and located to the right of
the "Select a Name" gadgets.  You select the gadget, type in the name,
and hit return.

Once you have a list of file names to choose from in the file name box,
there's a slider gadget to help you scroll around through the names.
The slider is to the right of the file names.  It has a knob which you
move to scroll through the names.  The knob will be different sizes
depending on the number of names in the file list.  If the knob is small,
this means that you can see only a small number of the total file names.
The smaller the knob, the more names there are to see.  On the other hand,
if you can see all the names in the list, the knob will fill up the
entire slider and you won't be able to move it.

To view the file names, you "grab" the slider's knob and move it up and down.
You grab the knob by pointing at it and pressing and holding the left mouse
button.  When you have grabbed the knob, you can move the pointer and
scan quickly through the list of file names.

Also, you can view the list of names one page at a time by clicking in the
area of the slider outside of the knob.  If you want fine control of your
movement through the file list, the up and down gadgets let you adjust
the list of names one name at a time.

Once you have found the file name that you want to choose, you select it
by pointing at it and clicking.  When you do this, the name will be
highlighted and it will appear in a box to the right of the "Select a Name"
gadgets.  When you've decided that this is really the name you wanted
to choose, pick the OK! gadget.  Another way to tell the program that
you're sure you want to select a certain file name is by double-clicking
on the file name in the same way that you double-click on a Workbench
icon.  Double-clicking is exactly the same as selecting a name and
then OK!

If you don't want to use the "Select a Name" gadgets, you can select a
name by typing the name into the string gadget labelled "Or Type a Name"
and then hitting return or clicking on the OK! gadget.  Hitting return
after typing the name you want is the same as selecting OK!

If you know what file name you want and you intend on typing it into
the string gadget, you can start typing as soon as the requester
appears.  You don't have to select the string gadget before you start
typing, and you don't have to wait for the wait pointer to change before
you hit return!

To view the files of a different disk, select the NEXT DISK gadget.
When you do, the name of the next disk is displayed in the Disk
string gadget and the disk is then searched.  If this disk isn't the
one you wanted, you can press NEXT DISK again even though you may be
seeing the wait pointer.  You can press NEXT DISK as many times as
you want until you see the name of the disk you want in the Disk gadget.
You can also type the name of the disk you want directly into the
Disk string gadget if you like.

You might notice that the ZZZ-cloud wait pointer looks a little different
from ones you're used to on the Amiga.  The File IO Requester's ZZZ-cloud
pointer has a small tab at the top left which allows you to continue
pointing and making selections even though the ZZZ-cloud is displayed.
The File IO Requester's ZZZ-cloud tells you that it's working, but it
doesn't make you wait.

You might notice also that the file names start appearing one by one
in the Select a Name gadget.  You can select one of these names even
before all of the names have been added to the list, though this can be
a bit tricky as they move around a lot.  While the list is being built
you can use the slider to look at what names have already been added.
If you see the name that you want to select, you can stop the building
of the file name list by clicking on a spot inside the requester but
outside of all the gadgets; for instance, if you click between the
OK! and CANCEL gadgets this will stop the list from being constructed.
Then you can select the name you want as usual.  To restart the building
of the file name list, click on either the Drawer or Disk string gadget
and hit return.




=============================================================================
=== PROGRAMMER'S REFERENCE ==================================================
=============================================================================

This section is for the programmer who wants to use the FileIO Requester
routines in her or his program.  Also, it's an introduction for those who
intend in delving into the guts of these routines.  For an overview of the
FileIO Requester routines, refer to the TECHNICAL REFERENCE section.

The Workbench names for DOS objects have been used in the FileIO Requester,
and are used throughout this document for simplicity.  For your reference,
a directory is referred to as a "drawer" and volumes, or DOS filesystem
devices, are referred to as "disks".

The phraseology on the requester itself was left vague intentionally
so that the same requester could be used to select names for both
input and output.

These are the subsections of this section:

    o  Basic Operation

    o  Multiple FileIOSupport Structures

    o  Workbench-style Filename Operations

    o  If You Don't Want Workbench-style Filename Operations

    o  FileIOSupport Flags

    o  GetFileIOName() is non-reentrant

    o  Procedure for Adding the FileIO Requester to Your Program




=== Basic Operation ========================================================

The FileIO routines base all of their work on a data structure called
the FileIOSupport structure.  You are allocated one of these structures
when you call the GetFileIOSupport() routine.  The structure is
initialized with reasonable default values for you.


The FileIOSupport structure is used when calling the GetFileIOName()
routine, which is the routine that actually presents the requester to
the user and gets the user's filename selection.

There are several flags and data fields in the FileIOSupport structure
that you may choose to initialize before calling GetFileIOName().
By setting or clearing these flags, you define how information is
to be presented to the user of your requester.  These flags are
described below in "FileIOSupport Flags".

Also, you may choose to give a title to your FileIO requester, which
title can illuminate the function of the requester.  For instance,
you may want to have one FileIOSupport structure used for input and
another for output.  You could give one the title "- SELECT INPUT FILE -"
and the other "- SELECT OUTPUT FILE -".  The title you supply is
centered at the top of the requester.  You supply a title by setting
the ReqTitle field of your FileIOSupport structure to point to
a null-terminated text string.  You can also set this field to NULL,
which is the default.  If this field is NULL, a default title is
displayed.

The GetFileIOName() function returns a BOOL value of TRUE or FALSE,
depending on whether the user completed or cancelled the filename
selection process.  If the return value is TRUE, you can find the
filename selected by the user in the FileName[] field of your
FileIOSupport structure.  The pathname to the file can be constructed
by calling the BuildFileIOPathname() function or by using the DiskName[]
and DrawerName[] fields.

You can call GetFileIOName() any number of times with the same FileIOSupport
structure.  The data in the FileIOSupport structure usually remains
valid between calls to GetFileIOName(), so with subsequent calls the
filename list doesn't have to be constructed anew.  This allows the
requester to appear very quickly because the usually-lengthy process
of accessing the disk is avoided.

The GetFileIOName() routine uses the GOOD_FILENAMES flag to discern
whether the data contained in your FileIOSupport structure is valid.
If GetFileIOName() sees that the flag is not set it builds the filename
list from scratch.  If the GOOD_FILENAMES is set, the list is not
recreated.

When GetFileIOSupport() creates a support structure for you, this flag
is cleared to specify that the support structure doesn't contain good
filenames.  Thus the first call to GetFileIOName() causes the filename
list to be constructed.  The GetFileIOName() function normally sets this
flag (unless the user has done something unusual or if GetFileIOName()
failed for some reason such as "out of memory"), so that subsequent
calls to GetFileIOName() work much more efficiently.

But you must do a bit work to support this efficiency.  You are obliged
to watch for IDCMP events of class DISKINSERTED and to clear the
GOOD_FILENAMES flag in any of your FileIOSupport structures whenever
you see this event.  The DISKINSERTED event occurs when the user has
switched around the disks.  When the user has changed disks you can't
be sure that your FileIO filename list is still valid, so as a courtesy
to the user you must cause the filename list to be reconstructed.

You can use the FileIO Requester to get the name of a file to be used
for output.  If you do and the specified file doesn't currently
exist, AmigaDOS will create it anew when you open it.  From the
FileIO Requester point of view, this means that a file now exists
that isn't in your FileIOSupport list.  To get the name in the list,
you can use the AddFileIOName() routine.  This routine adds a file
name to the list of file names currently in the specified
FileIOSupport structure.  The next time the FileIOSupport structure
is used for a call to GetFileIOName(), the new file name will apppear
alphabetized in with the other file names.  If the name is already in
the list when you call AddFileIOName() then nothing happens.
This allows you to call AddFileIOName() without worrying about
duplicate name redundancy, so you can skip checking whether or not
AmigaDOS has created a new file.

Finally, when you're finished with your FileIOSupport structure (usually
not until your program is terminating) then you call ReleaseFileIO() to
deallocate the structure and all the resources that it's accumulated.



=== Multiple FileIOSupport Structures =======================================

Your program can have more than one FileIOSupport structure at a time.
An example of why you would want more than one FileIOSupport structure:
you might want to have separate structures for getting input filenames
and output filenames from the user.  Another example:  you might have
one structure for letting the user select text files and another for
the selection of graphics files.

If you have more than one FileIOSupport structure, remember that you must
clear the GOOD_FILENAMES flag in all of them whenever you see Intuition's
DISKINSERTED IDCMP event class.

Also, regarding new disks, there's an extra procedure that you must follow.
If the user changes the disk while you've called GetFileIOName(), you
won't actually see a DISKINSERTED event (as the event will have been
processed by GetFileIOName() before control is returned to you).
So how will you know to clear the GOOD_FILENAMES flag in your other
structures?   Well, GetFileIOName() records the fact that a DISKINSERTED
event was handled by setting the DISK_HAS_CHANGED flag in your
FileIOSupport structure.  So on return from a call to GetFileIOName()
you should check to see whether your FileIOSupport structure has the
DISK_HAS_CHANGED flag set.  If it does, you should clear the
DISK_HAS_CHANGED flag in the structure and then clear the GOOD_FILENAMES
flag in all of your other FileIOSupport structures.  This assures that
when you call GetFileIOName() with any of your other support structures,
the filename lists will be reconstructed, as they should.



=== Workbench-style Filename Operations =====================================

You can have file names appear in the FileIO Requester using the same
rules that govern how files appear on the Workbench display, by using
the Workbench .info file mechanism.

If you intend on using Workbench pattern matching (or if you are going
to give the user the option) you must make sure that the constant
WBENCH_CODE is defined in the fileio.h file.  This includes the Workbench
code in the FileIO files when they are being compiled.  To attempt to
match Workbench patterns at run time, you must set the WBENCH_MATCH flag
in your FileIOSupport structure, as described below.

(By the way, if you don't intend on using Workbench-style pattern
matching and are interested in saving about 500 bytes of code size,
make sure you comment out the WBENCH_CODE definition.)

The Workbench .info file mechanism is a detailed topic that will not be
delved into here.  Please read the Amiga ROM Kernel Manual for a
description of the Workbench operation and data types.  What follows is a
cursory description of the Workbench technique, which is described only
well enough to explain how you can interact with it via your FileIOSupport
structure.

The Workbench program examines the directory of a disk and displays
icons for the files it finds that end with a ".info" suffix (hereafter
referred to as .info files).  The file names displayed beneath the
icons have the ".info" suffix removed.  The Workbench .info files
contain information regarding what type of data is contained in the
file (executable program, project data, et cetera).

You can choose to have only .info files displayed to the user (with
the ".info" suffix removed) in the same way that the Workbench does.
You get this by setting the WBENCH_MATCH flag.

You can further filter the names that appear if you wish.  There are
two techniques that you can employ for filtering which file names will
be added to the list:  you can ask for only those files that match a
particular Workbench object type and only those files that match a
particular tool type.

You elect to match the object type by setting the MATCH_OBJECTTYPE flag
in your FIleIOSupport structure.  The object types typically of interest
are WBTOOL and WBPROJECT.  By selecting one of these types, your
filename list will consist only of executable files or data files
respectively (except that all .info drawer names are always displayed).
If this is confusing, refer to the ROM Kernel manual for a discussion
of object types.

You can also request to match a Workbench tool type.  By matching tool
types, you can, for instance, have your file list display only those
data files that were created by a specific application.  See the section
entitled "The ToolTypes Array" in the Workbench chapter of the
ROM Kernel manual for a description of how tool types work.  You elect
to match tool types by setting the MATCH_TOOLTYPES flag in your
FileIOSupport structure.  The ToolTypes text that you must supply
should be written into the ToolTypes[] field of your FileIOSupport
structure.



=== If You Don't Want Workbench-style Filename Operations ===================

If you don't intend on using the Workbench-style pattern matching as
described above, then make sure you comment out the WBENCH_CODE definition.
This will result in a savings of about 500 bytes of code size.

If you comment out the WBENCH_CODE definition, then setting the WBENCH_MATCH
flag in your FileIOSupport structure will have no effect.



=== FileIOSupport Flags =====================================================

GOOD_FILENAMES
    This flag designates whether the filename data contained in the
    FileIOSupport is valid.  The flag is cleared by the
    GetFileIOSupport() function, and is usually set by the
    GetFileIOName() function.  When GetFileIOName() is called, this
    flag is checked and if it's set then the disk isn't reexamined for
    file names.  You should clear this flag in your FileIOSupport
    structures in two instances.  First, when you receive an Intuition
    IDCMP event of DISKINSERTED you should clear this flag in all of
    your FileIOSupport structures.  Second, if you have more than
    one FileIOSupport structure then on return from a call to
    GetFileIOName() you should check whether your support structure
    has the DISK_HAS_CHANGED flag set and if so you should clear
    the DISK_HAS_CHANGED flag in the structure and clear the
    GOOD_FILENAMES flag in all of your other FileIOSupport structures.


USE_VOLUME_NAMES
    When you leave this flag set, the AmigaDOS volume names will
    be used for the disk names in the requester.  If you clear
    this flag, the device names will be used instead.  What's a
    volume name and what's a device name?  Well, if you have your
    Workbench disk in the Amiga's internal drive, then the volume
    name of that disk is "Workbench:" and the device name is "DF0:".
    Which you choose to use is up to you.  Programmers are more
    familiar with device names.  The typical end-user is more
    familiar with volume names.  The default is to follow the
    Workbench convention and use volume names.


DISK_HAS_CHANGED
    If the user changes the disk while the FileIO Requester is
    being displayed, this flag is set in the FileIOSupport
    structure.  The only time you must pay attention to this
    flag is when you have multiple FileIOSupport structures.
    If you find that this flag has been set, you must clear
    this flag in your FileIOSupport structure and then clear
    the GOOD_FILENAMES flag in all of your other FileIOSupport
    structures.


DOUBLECLICK_OFF
    Normally, the user can double-click on a filename to select it.
    You may choose to disable this feature, for instance,
    when you want the user to be very certain about the
    filename selection (perhaps if the file is about to
    be destroyed, or something equally drastic).
    To disable double-clicking, set the DOUBLECLICK_OFF flag.
    Then the user will have to explicitly select OK! or type
    and filename and hit return for the selection to be made.


WBENCH_MATCH
    You set this flag to specify that you want Workbench-style
    .info file logic to be used when constructing the filename list.
    If you set this flag, only directory names and file names that
    pass the .info file tests will be displayed in the file name
    list.  See the "Workbench-style Filename Operations" section
    above for complete information.  This flag is cleared when
    your FileIOSupport structure is first created.


MATCH_OBJECTTYPE
    When you set this flag (and the WBENCH_MATCH flag), the
    DiskObjectType field of your FileIOSupport structure will
    be compared with the do_Type field of the .info file's
    DiskObject structure.  If they match, the file will be
    displayed.  Both the MATCH_TOOLTYPE and the MATCH_OBJECTTYPE
    flags can be set at the same time.  See the "Workbench-style
    Filename Operations" section above for complete information.


MATCH_TOOLTYPE
    If you set this flag (and the WBENCH_MATCH flag), then
    Workbench-style ToolType pattern matching will be performed
    and must be successful before the filename will be included
    in the list.  You specify your selection of ToolType in the
    FileIOSupport structure's ToolType[] field.  Both the
    MATCH_TOOLTYPE and the MATCH_OBJECTTYPE flags can be set at
    the same time.  See the "Workbench-style Filename Operations"
    section above for complete information.


RENAME_RAMDISK
    This is a flag that exists because of what seems to be a bug
    in 1.2 AmigaDOS.  For some reason, whenever one attempts to get
    an AmigaDOS Lock on the volume named "RAM DISK:" a software
    error occurs.  The problem doesn't necessarily lie in AmigaDOS,
    but the truth is that the error occurs with little provocation
    of AmigaDOS (for instance:
        dir "RAM DISK:"
    can and does crash the Amiga).  Until this bug is resolved,
    the FileIO code provides a work-around by supplying the
    RENAME_RAMDISK flag.  When the FileIO code is about to get
    a lock on a volume named "RAM DISK:", if this flag is set
    then the volume's name is changed internally to "RAM:" which
    locks successfully and does not crash the machine.
    This solution has a problem:  if the user has given the name
    "RAM DISK:" to some non-RAM: disk (such as a floppy) then this
    fix will fail and the floppy named "RAM DISK:" wouldn't be seen.
    This isn't too bad of a problem, because if the user has been
    silly enough to name a floppy "RAM DISK:" the user is probably
    experiencing lots of other problems already and this will
    provide just one more reason why one shouldn't name a floppy
    "RAM DISK:" don'cha know.
    With the current release of the Suite Book 1, the RENAME_RAMDISK
    flag is set when your FileIOSupport structure is first created.



=== GetFileIOName() is non-reentrant =======================================

If your program doesn't create tasks, or if you have multiple tasks
but only one of your tasks will call GetFileIOName() (which is almost
always the case), you can ignore the following information.

The GetFileIOName() routine is non-reentrant.  For the sake of memory
efficiency, it uses global data and variables rather than creating local
copies of these for each caller.

What this means is that if you have created a program that has more
than one task, GetFileIOName() cannot be called by more than one task
at a time.  This is not a problem for the grand majority of programs.

But if you have some application that would require calling this routine
asynchronously from multiple tasks, you'll have to implement some
quick semaphore arrangement to avoid collisions.  No big deal, actually.
See Exec semaphores for everything you need.




=== Procedure for Adding the FileIO Requester to Your Program ===============

This section presents a step-by-step procedure for incorporating
the FileIO Requester code into your own program.



Copy these FileIO files into your directory (and include them in your
makefile):
    alerts.c chipdata.c fileio.c filename.c filesupp.c globfio.c
    opendata.c pointers.c reqsupp.c strings.c volname.c
    fileio.h eglobfio.c



You have to include fileio.h in every file that refers to your
FileIOSupport structure.

    #include "fileio.h"



Are you going to provide your users with Workbench-style .info file
pattern matching?  If so, then go into fileio.h and make sure that
WBENCH_CODE is defined.

    #define WBENCH_CODE

If you're not going to provide Workbench .info file pattern matching,
verify that WBENCH_CODE isn't defined.  This make the FileIO code
about 500 bytes smaller.

    /* #define WBENCH_CODE */



Declare a pointer to a FileIOSupport structure, and then fill that
pointer with the address of one of the structures.

    struct FileIOSupport *FileIOSupp;

    FileIOSupp = GetFileIOSupport();



Your NewWindow structure should have the DISKINSERTED flag set along with
your other IDCMP flags.  Whenever you receive a DISKINSERTED event, you
should clear the GOOD_FILENAMES flag in every FileIOSupport structure you
control.  The following code could be added to the case switch where you
handle IDCMP events.

    switch (imessageclass)
        {
        case DISKINSERTED:
            /* You should clear the GOOD_FILENAMES flag
             * whenever you detect that a new disk was
             * inserted.
             */
            if (FileIOSupp)
                ClearFlag(FileIOSupp->Flags, GOOD_FILENAMES);
            break;
        }



When you want to present the FileIO Requester to the user, call
GetFileIOName().  If this routine returns TRUE, the user did not cancel the
operation.  The following code is an example of presenting the FileIO
Requester to the user and then reacting to the result.

    if (FileIOSupp)
        if (GetFileIOName(FileIOSupp, window))
            {
            UBYTE name[128];

            BuildFileIOPathname(FileIOSupp, &name[0]);

            /* Here do something like read or write the file.
             * If you write the file, you should call
             * AddFileIOName() if you've created a new file
             * or if you don't want to bother checking
             * whether or not it was a newly-created file.
             */
            if (writefile) AddFileIOName(FileIOSupp, &name[0]);
            }




Finally, when you're done with your FileIOSupport structure (usually when
you're program is exiting), you can free up the structure and its resources
with a simple call to ReleaseFileIO(), like this:

    if (FileIOSupp) ReleaseFileIO(FileIOSupp);




=============================================================================
=== DEMO PROGRAM NOTES ======================================================
=============================================================================

This section briefly describes the demo program that drives some of
the FileIO Requester's features.

If you invoke the program without a second argument, a window will be
opened in the Workbench screen.  If you invoke the program with any
second argument, a low-res screen will be opened for the requester window.

The program uses two FileIOSupport structures to demonstrate the
techniques that you should use when managing multiple FileIOSupports.
These techniques include processing DISKINSERTED events and discovering
on return from GetFileIOName() that the DISK_HAS_CHANGED flag is set.

The first support structure, fileio1, is used in its vanilla state
as created by GetFileIOSupport().  The other support structure, fileio2,
is initialized to do Workbench-style .info file handling where the
filename list will consist of only .info objects of type WBPROJECT.

Also, every time you insert a disk, the USE_VOLUME_NAMES flag in the
support structures is toggled, so that first you see volume names and
then you see device names.  This is for demonstration only; it's not
suggested that you use this technique in a real program.

Finally, when you do any of the selection techniques where you accept
your selection, the pathname to your selection is displayed in an
autorequester.  If you choose CANCEL to end the requester, nothing happens.

To stop the program, click in the window close gadget.





=============================================================================
=== TECHNICAL REFERENCE =====================================================
=============================================================================

This section gives you a brief outline of the FileIO software system files,
plus some scanty supplementary information.
Please refer to the source code itself.  The routines are commented
and, hopefully, reasonably laid out.


The FileIO files include:

    alerts.c
        Autorequester alert routines for emergency
        and shortcut communications

    chipdata.c
        Data for the Open requester that must be in chip memory

    eglobfio.c
        External global variable declarations

    fileio.c
        FileIO interface routines:  GetFileIOSupport(),
        GetFileIOName(), BuildFileIOPathname(), AddFileIOName(),
        and ReleaseFileIO()

    fileio.h
        The FileIO structure and constants definitions

    filename.c
        Routines that build the filename list

    filesupp.c
        Routines that create and manage the Open Requester

    globfio.c
        Global variable declarations

    main.c
        Demonstration program

    opendata.c
        Open Requester declarations

    pointers.c
        Pointer routines of the Amiga Programmer's Suite

    reqsupp.c
        DoRequest() routine of the Amiga Programmer's Suite

    strings.c
        RJ's general crude but illustrative string manipulation
        routines

    volname.c
        Routines that build the volume list





=== USING THE AMIGA PROGRAMMER'S SUITE ======================================

The Amiga Programmer's Suite Book 1 is copyrighted but freely distributable.
All copyright notices and all file headers must be retained intact.
The Amiga Programmer's Suite Book 1 may be compiled and assembled, and the
resultant object code may be included in any software product.  However, no
portion of the source listings or documentation of the Amiga Programmer's
Suite Book 1 may be distributed or sold for profit or in a for-profit
product without the written authorization of the author, RJ Mical.

If you use the Amiga Programmer's Suite, I wouldn't mind if you gave me
some mention somewhere.
Good luck!  Program hard, program well.    -RJ Mical




=== APPENDIX A:  FileIO Function Calls ======================================

CONTENTS:
   AddFileIOName()
   BuildFileIOPathname()
   GetFileIOSupport()
   GetFileIOName()
   ReleaseFileIO()





*** AddFileIOName() ******************************************************

NAME
    AddFileIOName  --  Add a file name to the names in a FileIOSupport


SYNOPSIS
    AddFileIOName(FileIOSupport, FileName);


FUNCTION
    This routine adds a file name to the list of file names currently
    in the specified FileIOSupport structure.  The next time the
    FileIOSupport structure is used for a call to GetFileIOName(), the
    new file name will apppear alphabetized in with the other file names.

    This routine will most often be used after a call to GetFileIOName()
    or some other routine where the user is allowed to specify the name
    of a file to be opened for output.  If the file is opened
    successfully, this routine will make sure that the name of the file
    is in the FileIOSupport structure.  This is important if the output
    file has been newly created; otherwise, without calling this
    routine, the next time the FileIOSupport structure is used the new
    file name would not appear even though the file exists.  If the name
    is already in the list when you call AddFileIOName() then nothing
    happens.  This allows you to call AddFileIOName() without worrying
    about duplicate name redundancy.

    Here's a typical sequence of events leading up to a call to
    AddFileIOName():

        First, get a FileIOSupport structure:
            fileio = GetFileIOSupport(...);

        When the user wants to write data, use GetFileIOName()
        to provide a convenient and consistent interface to
        the filesystem:
            goodfile = GetFileIOName(...);

        If the user has selected a name for output (in this example,
        goodfile will equal TRUE if the user selected a name), then
        open the file (possibly creating it) and then call
        AddFileIOName() to make sure the name is in the FileIOSupport
        structure's list:
            if (goodfile)
                {
                UBYTE filename[80];

                BuildFileIOPathname(fileio, &filename[0]);
                ... open filename, write it, close it ...
                if (filename opened successfully)
                    AddFileIOName(fileio, &filename[0]);
                }


INPUTS
    FileIOSupport = the address of a FileIOSupport structure
    FileName = the address of null-terminated text that is
        either a simple file name or a valid AmigaDOS pathname.


RESULT
    None


SEE ALSO
    GetFileIOName()
    GetFileIOSupport()





*** BuildFileIOPathname() ************************************************

NAME
    BuildFileIOPathname  --  Build a file pathname using a FileIO struct


SYNOPSIS
    BuildFileIOPathname(FileIOSupport, Buffer);


FUNCTION
    Builds the text for a pathname using the FileName[], DrawerName[] and
    DiskName[] fields of the specified FileIOSupport structure
    after the support structure has been used in a successful call
    to GetFileIOName().  Writes the text into the Buffer.


INPUTS
    FileIOSupport = the address of a FileIOSupport structure

    Buffer = address of the buffer to receive the file pathname


RESULT
    None


SEE ALSO
    GetFileIOName()





*** GetFileIOSupport() ***************************************************

NAME
    GetFileIO  --  Allocate and initialize a FileIOSupport structure


SYNOPSIS
    struct FileIOSupport *GetFileIOSupport();


FUNCTION
    Allocates and initializes a FileIOSupport structure for use with
    calls to GetFileIOName().

    You may want to further initialize the structure before calling
    GetFileIOName().  Refer to the FileIO documentation for more
    information.

    When you're done with the structure, call ReleaseFileIO().


INPUTS
    None


RESULT
    If all goes well, returns the address of a FileIOSupport structure.
    If anything goes wrong (usually out of memory), returns NULL.


EXAMPLE
    struct FileIOSupport *fileio;
    fileio = GetFileIOSupport();
    GetFileIOName(fileio, window);
    ReleaseFileIO(fileio);


BUGS
    None known


SEE ALSO
    GetFileIOName(), ReleaseFileIO()





*** GetFileIOName() ******************************************************

NAME
    GetFileIOName  --  Gets a file name for input/output from the user


SYNOPSIS
    BOOL GetFileIOName(FileIO, Window);


FUNCTION
    This routine creates a filename requester which allows the user
    to browse through the AmigaDOS filesystem and select one of
    the filenames found there.

    The FileIO argument is a pointer to a FileIOSupport structure,
    which is allocated and initialized for you via a call to
    GetFileIOSupport().
    You may preset the FileIO parameters before calling this routine,
    or you may leave them set at their default values.  See the FileIO
    documentation for complete details.

    The Window argument is the pointer to the window structure returned
    by a call to Intuition's OpenWindow() function.  As this routine
    opens a requester and requesters open in windows, you must have
    already opened a window before calling this routine, even if it's
    a window opened for no other purpose than to call this routine.

    This routine returns a BOOL value of TRUE or FALSE, depending on
    whether the user chose to accept or cancel the filename selection
    operation.  If TRUE, the filename selected by the user can be
    found in the FileIO structure FileName[] field.  This filename
    will have all leading and trailing blanks removed (in case the
    user typed in a filename with extraneous spaces).  Likewise,
    the pathname to the disk and drawer can be found in the text
    fields DiskName[] and DrawerName[].  You can construct
    the pathname using these text strings.  Also, you can call
    BuildFileIOPathname() to build the pathname automatically.

    There's a *lot* more to be said about this function.  Please
    read the documentation.

    NOTE:  This routine is not re-entrant.  What this means
    is that if you have created a program that has more than one task,
    this routine cannot be called by more than one task at a time.
    This is not a problem for the grand majority of programs.
    But if you have some application that would require calling this
    routine asynchronously from multiple tasks, you'll have to
    implement some quick semaphore arrangement to avoid collisions.
    No big deal, actually.  See Exec semaphores for everything you need.


INPUTS
    FileIO = pointer to a FileIOSupport structure, as allocated
        via a call to GetFileIOSupport()

    Window = pointer to a Window structure, as created via a call
        to Intuition's OpenWindow()


RESULT
    TRUE if the user decided that the filename selection was successful,
    FALSE if the user chose to cancel the operation


EXAMPLE
    if (GetFileIOName(fileio, window))
        ProcessFileName(&fileio->FileName[0]);


BUGS
    None known, though there could be some, and the disk selection
    subsystem logic is not perfectly polished (though it's believed
    to be bug-free).


SEE ALSO
    BuildFileIOPathname(), GetFileIOSupport(), ReleaseFileIO()





*** ReleaseFileIO() ******************************************************

NAME
    ReleaseFileIO  --  Release the FileIO structure and all local memory


SYNOPSIS
    ReleaseFileIO(FileIO);


FUNCTION
    Releases the FileIO structure by freeing all local memory attached
    to the structure and then freeing the structure itself.


INPUTS
    FileIO = the address of a FileIO structure


RESULT
    None


SEE ALSO
    GetFileIOSupport()